stream-to-promise

What is stream-to-promise?

The 'stream-to-promise' npm package is a utility that converts a stream into a promise. This is particularly useful when working with Node.js streams and you need to handle the completion of a stream operation using async/await or promise-based syntax.

What are stream-to-promise's main functionalities?

Convert Stream to Promise

This feature allows you to convert a readable stream into a promise. The promise resolves when the stream ends, making it easier to handle stream completion in an async/await context.

const streamToPromise = require('stream-to-promise');
const fs = require('fs');

async function readFile() {
  const readStream = fs.createReadStream('example.txt');
  await streamToPromise(readStream);
  console.log('Stream has ended');
}

readFile();

Handle Stream Errors

This feature demonstrates how to handle errors that occur during the stream operation. The promise will reject if the stream emits an 'error' event, allowing you to catch and handle the error using try/catch.

const streamToPromise = require('stream-to-promise');
const fs = require('fs');

async function readFile() {
  const readStream = fs.createReadStream('nonexistent.txt');
  try {
    await streamToPromise(readStream);
  } catch (error) {
    console.error('Stream error:', error);
  }
}

readFile();

Other packages similar to stream-to-promise

stream-to-array

'stream-to-array' is a package that collects all data from a stream into an array and returns a promise that resolves with the array. It is useful when you need to gather all chunks of data from a stream and process them together. Unlike 'stream-to-promise', which resolves when the stream ends, 'stream-to-array' also provides the collected data.

get-stream

'get-stream' is a package that converts a stream into a string, buffer, or array, and returns a promise that resolves with the collected data. It offers more flexibility in terms of the output format compared to 'stream-to-promise', which only resolves when the stream ends without providing the data.

promise-streams

'promise-streams' is a package that provides a set of utilities for working with streams using promises. It includes functions for collecting stream data, piping streams, and more. It offers a broader range of functionalities compared to 'stream-to-promise', which focuses solely on converting a stream to a promise.

README

stream-to-promise

Convert streams (readable or writable) to promises

Installing

npm install --save stream-to-promise

Examples

Readable Streams

streamToPromise(readableStream).then(function (buffer) {
  // buffer.length === 3
})
readableStream.emit('data', new Buffer())
readableStream.emit('data', new Buffer())
readableStream.emit('data', new Buffer())
readableStream.emit('end') // promise is resolved here

Writable Streams

streamToPromise(writableStream).then(function () {
  // resolves undefined
})
writableStream.write('data')
writableStream.end() // promise is resolved here

Error Handling

const err = new Error()
streamToPromise(stream).catch(function (error) {
  // error === err
})
stream.emit('error', err) // promise is rejected here